---
title: "VFD Custom Fields(Version-15)"
space: "vfd provider"
url: "https://support.aakvatech.com/VFD Provider/vfd-custom-fieldsversion-15"
updated: "2026-07-22"
---

# VFD Provider App - Custom Fields Documentation

## Table of Contents
1. [Overview](#overview)
2. [What is VFD (Virtual Fiscal Device)?](#what-is-vfd-virtual-fiscal-device)
3. [Custom Fields by Doctype](#custom-fields-by-doctype)
4. [Implementation Guide](#implementation-guide)
5. [Technical Reference](#technical-reference)

## Overview

The **VFD Provider App** is a Frappe/ERPNext application developed by Aakvatech Limited that enables businesses in Tanzania to comply with the Tanzania Revenue Authority (TRA) Virtual Fiscal Device (VFD) requirements. This app extends existing ERPNext doctypes with VFD-specific fields and functionality to ensure proper tax compliance and electronic receipt generation.

## What is VFD (Virtual Fiscal Device)?

### Purpose and Legal Requirement
A Virtual Fiscal Device (VFD) is a software-based solution mandated by the Tanzania Revenue Authority (TRA) for businesses to:
- Generate electronic fiscal receipts for all sales transactions
- Ensure proper VAT collection and reporting
- Maintain compliance with Tanzanian tax regulations
- Provide real-time transaction reporting to TRA

### How VFD Works
1. **Transaction Processing**: When a sale is made, the system generates transaction data
2. **VFD Submission**: Transaction details are sent to TRA's VFD servers
3. **Receipt Generation**: TRA returns a fiscal receipt number and verification URL
4. **Customer Receipt**: Customers receive receipts with TRA verification codes

### Business Benefits
- **Legal Compliance**: Meets TRA requirements for electronic receipts
- **Tax Accuracy**: Ensures correct VAT calculation and reporting
- **Audit Trail**: Maintains complete transaction history for tax audits
- **Customer Trust**: Provides verifiable receipts with TRA validation

## Custom Fields by Doctype

### 1. Customer Doctype

The VFD Provider app adds customer identification fields required for VFD compliance:

#### VFD Details Section
- **Field**: `vfd_details`
- **Type**: Section Break
- **Purpose**: Groups VFD-related customer information
- **Position**: After "Tax Withholding Category"

#### VFD Customer ID
- **Field**: `vfd_cust_id`
- **Type**: Data (Text)
- **Purpose**: Stores the customer's identification number for VFD receipts
- **Required**: Yes
- **Usage**: This ID appears on all VFD receipts for the customer

#### VFD Customer ID Type
- **Field**: `vfd_cust_id_type`
- **Type**: Select (Dropdown)
- **Purpose**: Specifies the type of identification document
- **Required**: Yes
- **Options**:
  - `1- TIN` (Tax Identification Number)
  - `2- Passport`
  - `3- Driving License`
  - `4- Voter ID`
  - `5- Aadhaar`
  - `6- Other`

**Why These Fields Matter**: TRA requires customer identification on all fiscal receipts. The ID type and number ensure proper customer tracking and compliance with tax regulations.

### 2. Sales Invoice Doctype

The Sales Invoice receives the most extensive VFD customizations, covering the entire VFD generation and tracking process:

#### VFD Generation Control

##### Generate VFD Button
- **Field**: `generate_vfd`
- **Type**: Button
- **Purpose**: Manually triggers VFD receipt generation
- **Visibility**: Only shown when:
  - Invoice is submitted (docstatus = 1)
  - Not marked as non-VFD invoice
  - VFD status is not "Success"
  - Not a return invoice
- **Position**: After "Due Date"

#### VFD Details Section
- **Field**: `vfd_details`
- **Type**: Section Break (Collapsible)
- **Purpose**: Groups all VFD-related information
- **Visibility**: Hidden from Healthcare Receptionists
- **Position**: After "Auth OTP"

#### VFD Transaction Information

##### VFD Date
- **Field**: `vfd_date`
- **Type**: Date
- **Purpose**: Records when the VFD receipt was generated
- **Read Only**: Yes (automatically set by system)

##### VFD Time
- **Field**: `vfd_time`
- **Type**: Time
- **Purpose**: Records the exact time of VFD generation
- **Read Only**: Yes (automatically set by system)

##### VFD Posting Info
- **Field**: `vfd_posting_info`
- **Type**: Link to "VFD Provider Posting"
- **Purpose**: Links to detailed VFD submission record
- **Read Only**: Yes

##### VFD Verification URL
- **Field**: `vfd_verification_url`
- **Type**: Data (Text, max 1000 characters)
- **Purpose**: Stores TRA-provided URL for receipt verification
- **Read Only**: Yes
- **Usage**: Customers can use this URL to verify receipt authenticity

#### VFD Control Numbers

##### VFD DC (Document Control)
- **Field**: `vfd_dc`
- **Type**: Integer
- **Purpose**: TRA-assigned document control number
- **Read Only**: Yes

##### VFD GC (Global Control)
- **Field**: `vfd_gc`
- **Type**: Integer
- **Purpose**: TRA-assigned global control number
- **Read Only**: Yes

#### VFD Status and Control

##### VFD Status
- **Field**: `vfd_status`
- **Type**: Select
- **Purpose**: Tracks VFD submission status
- **Default**: "Not Sent"
- **Options**:
  - `Not Sent`: Invoice not yet submitted to VFD
  - `Pending`: Submission in progress
  - `Failed`: Submission failed (requires retry)
  - `Success`: Successfully submitted to TRA
- **List View**: Visible in invoice lists for quick status checking
- **Filter**: Available as standard filter

##### Is Not VFD Invoice
- **Field**: `is_not_vfd_invoice`
- **Type**: Checkbox
- **Purpose**: Excludes invoice from VFD processing
- **Usage**: For internal transactions or non-taxable sales

##### Is Auto Generate VFD
- **Field**: `is_auto_generate_vfd`
- **Type**: Checkbox
- **Purpose**: Enables automatic VFD generation on invoice submission
- **Default**: Based on company settings

#### Customer Information (Fetched)

##### VFD Customer ID Type (Fetched)
- **Field**: `vfd_cust_id_type`
- **Type**: Data
- **Purpose**: Automatically fetched from Customer master
- **Source**: `customer.vfd_cust_id_type`

##### VFD Customer ID (Fetched)
- **Field**: `vfd_cust_id`
- **Type**: Data
- **Purpose**: Automatically fetched from Customer master
- **Source**: `customer.vfd_cust_id`

#### VFD Receipt Numbers

##### VFD RCTNUM
- **Field**: `vfd_rctnum`
- **Type**: Data
- **Purpose**: TRA-assigned receipt number
- **Read Only**: Yes

##### VFD RCTVNUM
- **Field**: `vfd_rctvnum`
- **Type**: Data
- **Purpose**: TRA-assigned receipt verification number
- **Read Only**: Yes

##### VFD SERIAL
- **Field**: `vfd_serial`
- **Type**: Data
- **Purpose**: VFD device serial number
- **Read Only**: Yes

**Why These Fields Matter**: Sales invoices must be submitted to TRA for VFD compliance. These fields track the entire process from submission to receipt generation, ensuring complete audit trails and legal compliance.

### 3. Item Tax Template Doctype

#### VFD Tax Code
- **Field**: `vfd_taxcode`
- **Type**: Select
- **Purpose**: Maps ERPNext tax templates to TRA tax categories
- **Position**: After "Taxes" table
- **Options**:
  - `1- Standard Rate (18%)`: Standard VAT rate
  - `2- Special Rate`: Special VAT rates
  - `3- Zero rated`: Zero-rated items
  - `4- Special Relief`: Tax relief items
  - `5- Exempt`: Tax-exempt items

**Why This Field Matters**: TRA requires specific tax codes for different item categories. This mapping ensures correct tax reporting and compliance with Tanzanian tax regulations.

### 4. Mode of Payment Doctype

#### VFD Payment Type
- **Field**: `vfd_pmttype`
- **Type**: Select
- **Purpose**: Maps payment methods to VFD payment types
- **Position**: After "Accounts" table
- **Options**:
  - `CASH`: Cash payments
  - `CHEQUE`: Check payments
  - `CCARD`: Credit card payments
  - `EMONEY`: Electronic money/mobile payments
  - `INVOICE`: Credit/invoice payments

**Why This Field Matters**: VFD receipts must specify payment methods using TRA-defined codes. This ensures accurate payment reporting and compliance.

## Implementation Guide

### Initial Setup

#### 1. Install VFD Provider App
```bash
# Install the app
bench get-app vfd_providers
bench install-app vfd_providers --site your-site-name
```

#### 2. Configure VFD Provider
1. Go to **VFD Provider** doctype
2. Create a new VFD Provider record
3. Set provider details (VFDPlus, TotalVFD, etc.)
4. Configure API endpoints and settings

#### 3. Company VFD Configuration
1. Go to **Company VFD Provider** doctype
2. Link your company to the VFD provider
3. Configure company-specific VFD settings

#### 4. Configure Tax Templates
1. Open **Item Tax Template** records
2. Set appropriate **VFD Tax Code** for each template
3. Ensure all items have proper tax templates assigned

#### 5. Configure Payment Methods
1. Open **Mode of Payment** records
2. Set appropriate **VFD Payment Type** for each method
3. Ensure all payment methods are properly mapped

### Daily Usage Workflow

#### Customer Setup
1. **Create/Update Customers**:
   - Enter **VFD Customer ID** (TIN, Passport, etc.)
   - Select **VFD Customer ID Type**
   - Save customer record

#### Invoice Processing
1. **Create Sales Invoice**:
   - Add items with proper tax templates
   - Select customer with VFD details
   - Choose payment method with VFD mapping

2. **VFD Generation**:
   - **Automatic**: Enable "Is Auto Generate VFD" for automatic submission
   - **Manual**: Click "Generate VFD" button after submission

3. **Monitor Status**:
   - Check **VFD Status** field
   - Review **VFD Verification URL** for customer
   - Verify receipt numbers are populated

#### Troubleshooting
- **Failed Status**: Check VFD Provider settings and retry
- **Missing Customer ID**: Update customer master data
- **Tax Code Errors**: Verify Item Tax Template configurations
- **Payment Type Issues**: Check Mode of Payment VFD mappings

### Best Practices

#### Data Management
- **Customer IDs**: Always collect proper identification from customers
- **Tax Templates**: Maintain accurate tax code mappings
- **Payment Methods**: Ensure all payment types are VFD-compliant

#### Compliance
- **Regular Monitoring**: Check VFD status on all invoices
- **Backup Procedures**: Maintain records of all VFD submissions
- **Error Handling**: Address failed submissions promptly

#### Performance
- **Batch Processing**: Use auto-generation for high-volume operations
- **Network Reliability**: Ensure stable internet for VFD submissions
- **System Monitoring**: Track VFD Provider Posting records for issues

## Technical Reference

### File Locations
- **Custom Fields Patch**: `apps/vfd_providers/vfd_providers/patches/custom_fields/vfd_providers_updated_custom_fields.py`
- **Hooks Configuration**: `apps/vfd_providers/vfd_providers/hooks.py`
- **VFD Logic**: `apps/vfd_providers/vfd_providers/utils/`

### Related Doctypes
- **VFD Provider**: Main provider configuration
- **VFD Provider Posting**: Transaction submission records
- **Total VFD Setting**: Provider-specific settings
- **Company VFD Provider**: Company-provider mapping

### Integration Points
- **Sales Invoice Events**: Automatic VFD generation on submission
- **Customer Validation**: ID information cleanup and validation
- **Tax Calculation**: Integration with ERPNext tax system
- **Payment Processing**: VFD payment type mapping

This documentation provides a complete reference for understanding and implementing the VFD Provider app's custom fields in ERPNext, ensuring proper VFD compliance for Tanzanian businesses.